home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Development Platforms / Apple II / Essentials / Technical.Notes / GSOS / TN.GSOS.004 < prev    next >
Encoding:
Text File  |  1991-06-28  |  8.8 KB  |  160 lines  |  [TEXT/pdos]
  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6.  
  7. GS/OS
  8. #4:          A GS/OS State of Mind
  9.  
  10. Revised by:  Matt Deatherage                                       March 1991
  11. Written by:  Matt Deatherage                                     January 1989
  12.  
  13. This Technical Note discusses GS/OS concepts and practices.
  14.  
  15. Changes singe July 1989:  Includes more information about thinking for
  16. non-ProDOS file systems.
  17. _____________________________________________________________________________
  18.  
  19.  
  20. Although GS/OS bears many similarities to ProDOS, GS/OS is a much
  21. wider-reaching operating system, working not only with multiple file systems
  22. but also with character devices.  Some things which work under ProDOS cause
  23. problems under GS/OS, and application programmers need to be aware of the
  24. differences, particularly those developing text-based programs.
  25.  
  26.  
  27. GS/OS Hints
  28.  
  29. Be aware of character devices.  A legal GS/OS pathname, perhaps entered by a
  30. user in response to a prompt, could map to a character device, with 
  31. potentially disastrous results.  Error $58, Not a Block Device, can protect 
  32. you against this on many calls, including Create, but you must still take 
  33. precaution.  DInfo tells you if a device is a character device or block 
  34. device; bit seven of the characteristics word is set if the device is a block 
  35. device.
  36.  
  37. Don't preprocess pathnames.  A user input routine which prevents users from
  38. entering pathnames that don't follow ProDOS syntax may help prevent Illegal
  39. Pathname Syntax errors, but it also keeps users from creating files on
  40. non-ProDOS disks with anything but ProDOS pathname syntax, and it could keep
  41. them from accessing files on non-ProDOS disks which they created with another
  42. GS/OS application.  Since the only FST which allowed you to write to a device
  43. under System Software 4.0 was ProDOS, you didn't see this problem right away.
  44. However, System Software 5.0 includes an AppleShare FST which, compared to
  45. ProDOS, is fast and loose with pathnames.  "How about an anti-ProDOS name?" 
  46. is a legal AppleShare filename.  To allow compatibility with present and 
  47. future non-ProDOS FSTs, Apple suggests you pass user-entered pathnames 
  48. directly to GS/OS, with no application preprocessing.
  49.  
  50. Remember that under GS/OS both colons and slashes are valid separators, and
  51. colons can only be separators.  In addition, all eight bits of each byte of a
  52. pathname are significant.  Refer to GS/OS Reference, Volume 1 for more
  53. information on GS/OS pathname syntax.  Using all eight bits of each byte may 
  54. be particularly difficult for text-based applications, which have no way to 
  55. force the standard Apple II character set to display characters such as sigma 
  56. or the copyright symbol; they can fiddle to get characters like the sterling 
  57. pound sign and an Apple.  Some programs may wish to adopt special 
  58. typographical conventions for these special characters while others may 
  59. choose not to create files with such characters in their names.  These 
  60. programs could present the user with a list of existing filenames (with some 
  61. substitution for the characters which are unavailable), while providing a 
  62. method of choosing one, to retrieve such files.  Any way around this problem 
  63. for a text-based program will be less than optimal.
  64.  
  65. Avoid the Text Tools and all slot dependencies.  Preliminary GS/OS
  66. documentation points to a System Service call named DYN_SLOT_ARBITER.  This
  67. mechanism, which is not fully implemented in System Software 5.0, eventually
  68. will allow the operating system to use internal ports and external slots for
  69. the same "slot" in the same session, instead of requiring the user to reboot
  70. the system to safely change between ports and slots.  Applications which have
  71. hard-coded slot dependencies (as the Text Tools unfortunately require) make
  72. this transition very difficult, both for GS/OS and for the applications and
  73. users.  We recommend that applications use the GS/OS loaded and generated
  74. character device drivers for text output.  A DInfo call will tell you what 
  75. slot or port a driver controls, and whether or not it is a character device.
  76.  
  77. Avoid other file system dependencies.  Many of the things ProDOS programmers
  78. are used to as facts of life just are not true any longer.  For example,
  79. filenames don't have to be 15 characters or less under GS/OS.  When making
  80. class one calls, GS/OS will tell you if you don't have enough room for the
  81. pathname by returning a Buffer Too Small error ($4F).  Avoiding file system
  82. dependencies means handling this error intelligently:  if you receive it,
  83. allocate more space for the buffer and try the call again.  GS/OS will tell 
  84. you how much space is needed.  If you absolutely must hard code pathnames, 
  85. suchas volume names, be sure to use the colon as the separator, because if 
  86. you donot, filenames with slashes will cause problems.  Similarly, don't 
  87. assume any ofthefollowing:
  88.  
  89. o   There can only be 51 files in the volume directory
  90. o   All devices are named ".Dn," where n is the device number
  91. o   All blocks are 512 bytes long
  92. o   All devices are block devices
  93. o   Any other ProDOS-specific characteristics
  94.  
  95. Your application may have hidden file system assumptions as well.  For 
  96. example, while a directory behaves like a directory under all GS/OS 
  97. filesystem translators, reading from a directory is not always as fast as it 
  98. isfor ProDOS disks.  ProDOS directories are fairly linear and can be searched 
  99. quickly; but other file systems may have more complicated directory 
  100. structures (HFS and AppleShare, for example, have B-trees that store 
  101. directory entries in alphabetical order).  To get optimal speed, try to do as 
  102. many GetDirEntry calls as you can in succession without other GS/OS calls 
  103. intervening this allows Apple to optimize file system translators for fast 
  104. directory reading.
  105.  
  106. Also remember that other file systems may not support the concept oforderable 
  107. directories, so don't depend on directory order in your application.
  108.  
  109. Don't hog all of the memory.  While this is never a good idea on the IIgs, 
  110. it's even worse under GS/OS.  To process things like pathnames, GS/OS 
  111. allocates memory through the Memory Manager.  If you've allocated all of 
  112. available memory (i.e., for a disk copy procedure), GS/OS will be forced to 
  113. return an Out of Memory error ($54).  If the condition is so severe that 
  114. GS/OS can no longer function, it will return a fatal GS/OS error with an ID = 
  115. 2, and the user will be asked to restart the system.
  116.  
  117. (A common cause of fatal GS/OS error 2 during development is using a length 
  118. byte instead of a length word on a class one string.  Doing so almost always 
  119. causes the first word to be greater than 8K, which is the maximum length of 
  120. pathnames under GS/OS.  GS/OS then dies for your enjoyment, as it is unableto 
  121. allocate the memory for the pathname because it's too big, even if more than 
  122. 8K is available.)
  123.  
  124. Hard code as little as possible.  Even seemingly static things like device 
  125. names should not be hard coded, since a new loaded driver could change the 
  126. name of the same device at any time.  Also, it may be possible in the future 
  127. for users to rename devices.
  128.  
  129. Only ask for the access you need.  If you're just going to read a file, make 
  130. a call to Open the file with read permission only.  In file systems where 
  131. access privileges mean more than they traditionally have in ProDOS (where 
  132. things are usually "Locked" or "Unlocked"), this could save some trouble.  
  133. For example, AppleShare allows the same file to be opened multiple times as 
  134. long as each open is with read-only access.  If your program is only going to 
  135. read a file, opening it with read and write access needlessly denies others 
  136. on the server access to the file.
  137.  
  138. Copy all GS/OS information with files.  Applications that copy files need 
  139. todo more than copy the data fork of the file.  If the file is extended, the 
  140. resource fork of the file should be copied as well.  In addition, when 
  141. requested, each FST returns an option_list that contains information specific 
  142. to the host file system that GS/OS does not use (i.e., AppleShare's 
  143. option_list includes Finder information and access privileges).  Calls to 
  144. GetFileInfo and Open can return the option_list, while a call to SetFileInfo 
  145. can set it.  An FST will not set parameters in the option_list which should 
  146. not be altered (just as SetFileInfo skips the EOF fields in GetFileInfo 
  147. records).  To ensure that the duplicate has as much host file system 
  148. information from the original as can reasonably be transferred, always copy 
  149. the option_list.
  150.  
  151. However, if you want to change something in an existing file's GetFileInfo 
  152. list, do not use an option_list.  The option_list could override the other 
  153. parameters to SetFileInfo without your knowledge.
  154.  
  155.  
  156. Further Reference
  157. _____________________________________________________________________________
  158.   o  GS/OS Reference, Volumes 1 and 2
  159.  
  160.